   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Glyph Types
===========

   Each glyph has a particular type, which controls how the glyph's
image is generated.  Each glyph type has a corresponding list of
allowable image instance types that can be generated.  When you call
`glyph-image-instance' to retrieve the image instance of a glyph,
XEmacs does the equivalent of calling `make-image-instance' and passing
in DEST-TYPES the list of allowable image instance types for the
glyph's type.

   * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
     extent, in the modeline, and in the toolbar.  Their image can be
     instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
     and `subwindow'.

   * `pointer' glyphs can be used to specify the mouse pointer.  Their
     image can be instantiated as `pointer'.

   * `icon' glyphs can be used to specify the icon used when a frame is
     iconified.  Their image can be instantiated as `mono-pixmap' and
     `color-pixmap'.

 - Function: glyph-type GLYPH
     This function returns the type of the given glyph.  The return
     value will be a symbol, one of `buffer', `pointer', or `icon'.

 - Function: valid-glyph-type-p GLYPH-TYPE
     Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.

 - Function: glyph-type-list
     This function returns a list of valid glyph types.

 - Function: buffer-glyph-p OBJECT
     This function returns non-`nil' if OBJECT is a glyph of type
     `buffer'.

 - Function: icon-glyph-p OBJECT
     This function returns non-`nil' if OBJECT is a glyph of type
     `icon'.

 - Function: pointer-glyph-p OBJECT
     This function returns non-`nil' if OBJECT is a glyph of type
     `pointer'.

Mouse Pointer
=============

   The shape of the mouse pointer when over a particular section of a
frame is controlled using various glyph variables.  Since the image of
a glyph is a specifier, it can be controlled on a per-buffer,
per-frame, per-window, or per-device basis.

   You should use `set-glyph-image' to set the following variables,
*not* `setq'.

 - Glyph: text-pointer-glyph
     This variable specifies the shape of the mouse pointer when over
     text.

 - Glyph: nontext-pointer-glyph
     This variable specifies the shape of the mouse pointer when over a
     buffer, but not over text.  If unspecified in a particular domain,
     `text-pointer-glyph' is used.

 - Glyph: modeline-pointer-glyph
     This variable specifies the shape of the mouse pointer when over
     the modeline.  If unspecified in a particular domain,
     `nontext-pointer-glyph' is used.

 - Glyph: selection-pointer-glyph
     This variable specifies the shape of the mouse pointer when over a
     selectable text region.  If unspecified in a particular domain,
     `text-pointer-glyph' is used.

 - Glyph: gc-pointer-glyph
     This variable specifies the shape of the mouse pointer when a
     garbage collection is in progress.  If the selected window is on a
     window system and this glyph specifies a value (i.e. a pointer
     image instance) in the domain of the selected window, the pointer
     will be changed as specified during garbage collection.
     Otherwise, a message will be printed in the echo area, as
     controlled by `gc-message'.

 - Glyph: busy-pointer-glyph
     This variable specifies the shape of the mouse pointer when XEmacs
     is busy.  If unspecified in a particular domain, the pointer is
     not changed when XEmacs is busy.

 - Glyph: menubar-pointer-glyph
     This variable specifies the shape of the mouse pointer when over
     the menubar.  If unspecified in a particular domain, the
     window-system-provided default pointer is used.

 - Glyph: scrollbar-pointer-glyph
     This variable specifies the shape of the mouse pointer when over a
     scrollbar.  If unspecified in a particular domain, the
     window-system-provided default pointer is used.

 - Glyph: toolbar-pointer-glyph
     This variable specifies the shape of the mouse pointer when over a
     toolbar.  If unspecified in a particular domain,
     `nontext-pointer-glyph' is used.

   Internally, these variables are implemented in
`default-mouse-motion-handler', and thus only take effect when the
mouse moves.  That function calls `set-frame-pointer', which sets the
current mouse pointer for a frame.

 - Function: set-frame-pointer FRAME IMAGE-INSTANCE
     This function sets the mouse pointer of FRAME to the given pointer
     image instance.  You should not call this function directly.  (If
     you do, the pointer will change again the next time the mouse
     moves.)

Redisplay Glyphs
================

 - Glyph: truncation-glyph
     This variable specifies what is displayed at the end of truncated
     lines.

 - Glyph: continuation-glyph
     This variable specifies what is displayed at the end of wrapped
     lines.

 - Glyph: octal-escape-glyph
     This variable specifies what to prefix character codes displayed
     in octal with.

 - Glyph: hscroll-glyph
     This variable specifies what to display at the beginning of
     horizontally scrolled lines.

 - Glyph: invisible-text-glyph
     This variable specifies what to use to indicate the presence of
     invisible text.  This is the glyph that is displayed when an
     ellipsis is called for, according to `selective-display-ellipses'
     or `buffer-invisibility-spec').  Normally this is three dots
     ("...").

 - Glyph: control-arrow-glyph
     This variable specifies what to use as an arrow for control
     characters.

Subwindows
==========

   Subwindows are not currently implemented.

 - Function: subwindowp OBJECT
     This function returns non-`nil' if OBJECT is a subwindow.

Annotations
***********

   An "annotation" is a pixmap or string that is not part of a buffer's
text but is displayed next to a particular location in a buffer.
Annotations can be displayed intermixed with text, in any whitespace at
the beginning or end of a line, or in a special area at the left or
right side of the frame called a "margin", whose size is controllable.
Annotations are implemented using extents (see Extents.); but you
can work with annotations without knowing how extents work.

Annotation Basics
=================

   Marginal annotations are notes associated with a particular location
in a buffer.  They may be displayed in a margin created on the
left-hand or right-hand side of the frame, in any whitespace at the
beginning or end of a line, or inside of the text itself.  Every
annotation may have an associated action to be performed when the
annotation is selected.  The term "annotation" is used to refer to an
individual note.  The term "margin" is generically used to refer to the
whitespace before the first character on a line or after the last
character on a line.

   Each annotation has the following characteristics:
GLYPH
     This is a glyph object and is used as the displayed representation
     of the annotation.

DOWN-GLYPH
     If given, this glyph is used as the displayed representation of
     the annotation when the mouse is pressed down over the annotation.

FACE
     The face with which to display the glyph.

SIDE
     Which side of the text (left or right) the annotation is displayed
     at.

ACTION
     If non-`nil', this field must contain a function capable of being
     the first argument to `funcall'.  This function is normally
     evaluated with a single argument, the value of the DATA field,
     each time the annotation is selected.  However, if the WITH-EVENT
     parameter to `make-annotation' is non-`nil', the function is
     called with two arguments.  The first argument is the same as
     before, and the second argument is the event (a button-up event,
     usually) that activated the annotation.

DATA
     Not used internally.  This field can contain any E-Lisp object.
     It is passed as the first argument to ACTION described above.

MENU
     A menu displayed when the right mouse button is pressed over the
     annotation.

   The margin is divided into "outside" and "inside".  The outside
margin is space on the left or right side of the frame which normal text
cannot be displayed in.  The inside margin is that space between the
leftmost or rightmost point at which text can be displayed and where the
first or last character actually is.

   There are four different "layout types" which affect the exact
location an annotation appears.

`outside-margin'
     The annotation is placed in the outside margin area. as close as
     possible to the edge of the frame.  If the outside margin is not
     wide enough for an annotation to fit, it is not displayed.

`inside-margin'
     The annotation is placed in the inside margin area, as close as
     possible to the edge of the frame.  If the inside margin is not
     wide enough for the annotation to fit, it will be displayed using
     any available outside margin space if and only if the specifier
     `use-left-overflow' or `use-right-overflow' (depending on which
     side the annotation appears in) is non-`nil'.

`whitespace'
     The annotation is placed in the inside margin area, as close as
     possible to the first or last non-whitespace character on a line.
     If the inside margin is not wide enough for the annotation to fit,
     it will be displayed if and only if the specifier
     `use-left-overflow' or `use-right-overflow' (depending on which
     side the annotation appears in) is non-`nil'.

`text'
     The annotation is placed at the position it is inserted.  It will
     create enough space for itself inside of the text area.  It does
     not take up a place in the logical buffer, only in the display of
     the buffer.

   The current layout policy is that all `whitespace' annotations are
displayed first.  Next, all `inside-margin' annotations are displayed
using any remaining space.  Finally as many `outside-margin'
annotations are displayed as possible.  The `text' annotations will
always display as they create their own space to display in.

Annotation Primitives
=====================

 - Function: make-annotation GLYPH &optional POSITION LAYOUT BUFFER
          WITH-EVENT D-GLYPH RIGHTP
     This function creates a marginal annotation at position POS in
     BUFFER.  The annotation is displayed using GLYPH, which should be
     a glyph object or a string, and is positioned using layout policy
     LAYOUT.  If POS is `nil', point is used.  If LAYOUT is `nil',
     `whitespace' is used.  If BUFFER is `nil', the current buffer is
     used.

     If WITH-EVENT is non-`nil', then when an annotation is activated,
     the triggering event is passed as the second arg to the annotation
     function.  If D-GLYPH is non-`nil' then it is used as the glyph
     that will be displayed when button1 is down.  If RIGHTP is
     non-`nil' then the glyph will be displayed on the right side of
     the buffer instead of the left.

     The newly created annotation is returned.

 - Function: delete-annotation ANNOTATION
     This function removes ANNOTATION from its buffer.  This does not
     modify the buffer text.

 - Function: annotationp ANNOTATION
     This function returns `t' if ANNOTATION is an annotation, `nil'
     otherwise.

Annotation Properties
=====================

 - Function: annotation-glyph ANNOTATION
     This function returns the glyph object used to display ANNOTATION.

 - Function: set-annotation-glyph ANNOTATION GLYPH &optional LAYOUT SIDE
     This function sets the glyph of ANNOTATION to GLYPH, which should
     be a glyph object.  If LAYOUT is non-`nil', set the layout policy
     of ANNOTATION to LAYOUT.  If SIDE is `left' or `right', change the
     side of the buffer at which the annotation is displayed to the
     given side.  The new value of `annotation-glyph' is returned.

 - Function: annotation-down-glyph ANNOTATION
     This function returns the glyph used to display ANNOTATION when
     the left mouse button is depressed on the annotation.

 - Function: set-annotation-down-glyph ANNOTATION GLYPH
     This function returns the glyph used to display ANNOTATION when
     the left mouse button is depressed on the annotation to GLYPH,
     which should be a glyph object.

 - Function: annotation-face ANNOTATION
     This function returns the face associated with ANNOTATION.

 - Function: set-annotation-face ANNOTATION FACE
     This function sets the face associated with ANNOTATION to FACE.

 - Function: annotation-layout ANNOTATION
     This function returns the layout policy of ANNOTATION.

 - Function: set-annotation-layout ANNOTATION LAYOUT
     This function sets the layout policy of ANNOTATION to LAYOUT.

 - Function: annotation-side ANNOTATION
     This function returns the side of the buffer that ANNOTATION is
     displayed on.  Return value is a symbol, either `left' or `right'.

 - Function: annotation-data ANNOTATION
     This function returns the data associated with ANNOTATION.

 - Function: set-annotation-data ANNOTATION DATA
     This function sets the data field of ANNOTATION to DATA.  DATA is
     returned.

 - Function: annotation-action ANNOTATION
     This function returns the action associated with ANNOTATION.

 - Function: set-annotation-action ANNOTATION ACTION
     This function sets the action field of ANNOTATION to ACTION.
     ACTION is returned..

 - Function: annotation-menu ANNOTATION
     This function returns the menu associated with ANNOTATION.

 - Function: set-annotation-menu ANNOTATION MENU
     This function sets the menu associated with ANNOTATION to MENU.
     This menu will be displayed when the right mouse button is pressed
     over the annotation.

 - Function: annotation-visible ANNOTATION
     This function returns `t' if there is enough available space to
     display ANNOTATION, `nil' otherwise.

 - Function: annotation-width ANNOTATION
     This function returns the width of ANNOTATION in pixels.

 - Function: hide-annotation ANNOTATION
     This function removes ANNOTATION's glyph, making it invisible.

 - Function: reveal-annotation ANNOTATION
     This function restores ANNOTATION's glyph, making it visible.

Locating Annotations
====================

 - Function: annotations-in-region START END BUFFER
     This function returns a list of all annotations in BUFFER which
     are between START and END inclusively.

 - Function: annotations-at &optional POSITION BUFFER
     This function returns a list of all annotations at POSITION in
     BUFFER.  If POSITION is `nil' point is used.  If BUFFER is `nil'
     the current buffer is used.

 - Function: annotation-list &optional BUFFER
     This function returns a list of all annotations in BUFFER.  If
     BUFFER is `nil', the current buffer is used.

 - Function: all-annotations
     This function returns a list of all annotations in all buffers in
     existence.

Margin Primitives
=================

   The margin widths are controllable on a buffer-local, window-local,
frame-local, device-local, or device-type-local basis through the use
of specifiers.  See Specifiers.

 - Specifier: left-margin-width
     This is a specifier variable controlling the width of the left
     outside margin, in characters.  Use `set-specifier' to change its
     value.

 - Specifier: right-margin-width
     This is a specifier variable controlling the width of the right
     outside margin, in characters.  Use `set-specifier' to change its
     value.

 - Specifier: use-left-overflow
     If non-`nil', use the left outside margin as extra whitespace when
     displaying `whitespace' and `inside-margin' annotations.  Defaults
     to `nil'.  This is a specifier variable; use `set-specifier' to
     change its value.

 - Specifier: use-right-overflow
     If non-`nil', use the right outside margin as extra whitespace when
     displaying `whitespace' and `inside-margin' annotations.  Defaults
     to `nil'.  This is a specifier variable; use `set-specifier' to
     change its value.

 - Function: window-left-margin-pixel-width &optional WINDOW
     This function returns the width in pixels of the left outside
     margin of WINDOW.  If WINDOW is `nil', the selected window is
     assumed.

 - Function: window-right-margin-pixel-width &optional WINDOW
     This function returns the width in pixels of the right outside
     margin of WINDOW.  If WINDOW is `nil', the selected window is
     assumed.

   The margin colors are controlled by the faces `left-margin' and
`right-margin'.  These can be set using the X resources
`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
likewise for the right margin.

Annotation Hooks
================

   The following three hooks are provided for use with the marginal
annotations:

`before-delete-annotation-hook'
     This hook is called immediately before an annotation is destroyed.
     It is passed a single argument, the annotation being destroyed.

`after-delete-annotation-hook'
     This normal hook is called immediately after an annotation is
     destroyed.

`make-annotation-hook'
     This hook is called immediately after an annotation is created.
     It is passed a single argument, the newly created annotation.

Emacs Display
*************

   This chapter describes a number of other features related to the
display that XEmacs presents to the user.

Refreshing the Screen
=====================

   The function `redraw-frame' redisplays the entire contents of a
given frame.  See Frames.

 - Function: redraw-frame FRAME
     This function clears and redisplays frame FRAME.

   Even more powerful is `redraw-display':

 - Command: redraw-display &optional DEVICE
     This function redraws all frames on DEVICE marked as having their
     image garbled.  DEVICE defaults to the selected device.  If DEVICE
     is `t', all devices will have their frames checked.

   Processing user input takes absolute priority over redisplay.  If you
call these functions when input is available, they do nothing
immediately, but a full redisplay does happen eventually--after all the
input has been processed.

   Normally, suspending and resuming XEmacs also refreshes the screen.
Some terminal emulators record separate contents for display-oriented
programs such as XEmacs and for ordinary sequential display.  If you are
using such a terminal, you might want to inhibit the redisplay on
resumption.  See Suspending XEmacs.

 - Variable: no-redraw-on-reenter
     This variable controls whether XEmacs redraws the entire screen
     after it has been suspended and resumed.  Non-`nil' means yes,
     `nil' means no.

   The above functions do not actually cause the display to be updated;
rather, they clear out the internal display records that XEmacs
maintains, so that the next time the display is updated it will be
redrawn from scratch.  Normally this occurs the next time that
`next-event' or `sit-for' is called; however, a display update will not
occur if there is input pending.  See Command Loop.

 - Command: force-redisplay
     This function causes an immediate update of the display in all
     circumstances, whether or not input is pending. (This function does
     not exist in FSF Emacs.)

 - Function: force-cursor-redisplay
     This function causes an immediate update of the cursor on the
     selected frame. (This function does not exist in FSF Emacs.)

Truncation
==========

   When a line of text extends beyond the right edge of a window, the
line can either be truncated or continued on the next line.  When a line
is truncated, this is normally shown with a `\' in the rightmost column
of the window on X displays, and with a `$' on TTY devices.  When a
line is continued or "wrapped" onto the next line, this is shown with a
curved arrow in the rightmost column of the window (or with a `\' on
TTY devices).  The additional screen lines used to display a long text
line are called "continuation" lines.

   Normally, whenever line truncation is in effect for a particular
window, a horizontal scrollbar is displayed in that window if the
device supports scrollbars.  See Scrollbars.

   Note that continuation is different from filling; continuation
happens on the screen only, not in the buffer contents, and it breaks a
line precisely at the right margin, not at a word boundary.  See
Filling.

 - User Option: truncate-lines
     This buffer-local variable controls how XEmacs displays lines that
     extend beyond the right edge of the window.  If it is non-`nil',
     then XEmacs does not display continuation lines; rather each line
     of text occupies exactly one screen line, and a backslash appears
     at the edge of any line that extends to or beyond the edge of the
     window.  The default is `nil'.

     If the variable `truncate-partial-width-windows' is non-`nil',
     then truncation is always used for side-by-side windows (within one
     frame) regardless of the value of `truncate-lines'.

 - User Option: default-truncate-lines
     This variable is the default value for `truncate-lines', for
     buffers that do not have local values for it.

 - User Option: truncate-partial-width-windows
     This variable controls display of lines that extend beyond the
     right edge of the window, in side-by-side windows (see Splitting Windows.).
     If it is non-`nil', these lines are truncated;
     otherwise, `truncate-lines' says what to do with them.

   The backslash and curved arrow used to indicate truncated or
continued lines are only defaults, and can be changed.  These images
are actually glyphs (see Glyphs.).  XEmacs provides a great deal of
flexibility in how glyphs can be controlled. (This differs from FSF
Emacs, which uses display tables to control these images.)

   For details, see Redisplay Glyphs.

The Echo Area
=============

   The "echo area" is used for displaying messages made with the
`message' primitive, and for echoing keystrokes.  It is not the same as
the minibuffer, despite the fact that the minibuffer appears (when
active) in the same place on the screen as the echo area.  The `XEmacs
Reference Manual' specifies the rules for resolving conflicts between
the echo area and the minibuffer for use of that screen space (see
The Minibuffer (emacs)).  Error messages appear in the echo
area; see Errors.

   You can write output in the echo area by using the Lisp printing
functions with `t' as the stream (see Output Functions.), or as
follows:

 - Function: message STRING &rest ARGUMENTS
     This function displays a one-line message in the echo area.  The
     argument STRING is similar to a C language `printf' control
     string.  See `format' in String Conversion, for the details
     on the conversion specifications.  `message' returns the
     constructed string.

     In batch mode, `message' prints the message text on the standard
     error stream, followed by a newline.

     If STRING is `nil', `message' clears the echo area.  If the
     minibuffer is active, this brings the minibuffer contents back onto
     the screen immediately.

          (message "Minibuffer depth is %d."
                   (minibuffer-depth))
           -| Minibuffer depth is 0.
          => "Minibuffer depth is 0."

          ---------- Echo Area ----------
          Minibuffer depth is 0.
          ---------- Echo Area ----------

   Some of the messages displayed in the echo area are also recorded in
the ` *Message-Log*' buffer.

 - User Option: log-message-max-size
     This variable specifies the maximum size of `* Message-Log*'
     buffer.

 - Variable: echo-keystrokes
     This variable determines how much time should elapse before command
     characters echo.  Its value must be an integer, which specifies the
     number of seconds to wait before echoing.  If the user types a
     prefix key (such as `C-x') and then delays this many seconds before
     continuing, the prefix key is echoed in the echo area.  Any
     subsequent characters in the same command will be echoed as well.

     If the value is zero, then command input is not echoed.

 - Variable: cursor-in-echo-area
     This variable controls where the cursor appears when a message is
     displayed in the echo area.  If it is non-`nil', then the cursor
     appears at the end of the message.  Otherwise, the cursor appears
     at point--not in the echo area at all.

     The value is normally `nil'; Lisp programs bind it to `t' for
     brief periods of time.

Invisible Text
==============

   You can make characters "invisible", so that they do not appear on
the screen, with the `invisible' property.  This can be either a text
property or a property of an overlay.

   In the simplest case, any non-`nil' `invisible' property makes a
character invisible.  This is the default case--if you don't alter the
default value of `buffer-invisibility-spec', this is how the
`invisibility' property works.  This feature is much like selective
display (see Selective Display.), but more general and cleaner.

   More generally, you can use the variable `buffer-invisibility-spec'
to control which values of the `invisible' property make text
invisible.  This permits you to classify the text into different subsets
in advance, by giving them different `invisible' values, and
subsequently make various subsets visible or invisible by changing the
value of `buffer-invisibility-spec'.

   Controlling visibility with `buffer-invisibility-spec' is especially
useful in a program to display the list of entries in a data base.  It
permits the implementation of convenient filtering commands to view
just a part of the entries in the data base.  Setting this variable is
very fast, much faster than scanning all the text in the buffer looking
for properties to change.

 - Variable: buffer-invisibility-spec
     This variable specifies which kinds of `invisible' properties
     actually make a character invisible.

    `t'
          A character is invisible if its `invisible' property is
          non-`nil'.  This is the default.

    a list
          Each element of the list makes certain characters invisible.
          Ultimately, a character is invisible if any of the elements
          of this list applies to it.  The list can have two kinds of
          elements:

         `ATOM'
               A character is invisible if its `invisible' propery value
               is ATOM or if it is a list with ATOM as a member.

         `(ATOM . t)'
               A character is invisible if its `invisible' propery value
               is ATOM or if it is a list with ATOM as a member.
               Moreover, if this character is at the end of a line and
               is followed by a visible newline, it displays an
               ellipsis.

   Ordinarily, commands that operate on text or move point do not care
whether the text is invisible.  However, the user-level line motion
commands explicitly ignore invisible newlines.

Selective Display
=================

   "Selective display" is a pair of features that hide certain lines on
the screen.

   The first variant, explicit selective display, is designed for use in
a Lisp program.  The program controls which lines are hidden by altering
the text.  Outline mode has traditionally used this variant.  It has
been partially replaced by the invisible text feature (see Invisible Text.);
there is a new version of Outline mode which uses that
instead.

   In the second variant, the choice of lines to hide is made
automatically based on indentation.  This variant is designed to be a
user-level feature.

   The way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m).  The text that
was formerly a line following that newline is now invisible.  Strictly
speaking, it is temporarily no longer a line at all, since only newlines
can separate lines; it is now part of the previous line.

   Selective display does not directly affect editing commands.  For
example, `C-f' (`forward-char') moves point unhesitatingly into
invisible text.  However, the replacement of newline characters with
carriage return characters affects some editing commands.  For example,
`next-line' skips invisible lines, since it searches only for newlines.
Modes that use selective display can also define commands that take
account of the newlines, or that make parts of the text visible or
invisible.

   When you write a selectively displayed buffer into a file, all the
control-m's are output as newlines.  This means that when you next read
in the file, it looks OK, with nothing invisible.  The selective display
effect is seen only within XEmacs.

 - Variable: selective-display
     This buffer-local variable enables selective display.  This means
     that lines, or portions of lines, may be made invisible.

        * If the value of `selective-display' is `t', then any portion
          of a line that follows a control-m is not displayed.

        * If the value of `selective-display' is a positive integer,
          then lines that start with more than that many columns of
          indentation are not displayed.

     When some portion of a buffer is invisible, the vertical movement
     commands operate as if that portion did not exist, allowing a
     single `next-line' command to skip any number of invisible lines.
     However, character movement commands (such as `forward-char') do
     not skip the invisible portion, and it is possible (if tricky) to
     insert or delete text in an invisible portion.

     In the examples below, we show the *display appearance* of the
     buffer `foo', which changes with the value of `selective-display'.
     The *contents* of the buffer do not change.

          (setq selective-display nil)
               => nil

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
            3n this column
            3n this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

          (setq selective-display 2)
               => 2

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

 - Variable: selective-display-ellipses
     If this buffer-local variable is non-`nil', then XEmacs displays
     `...' at the end of a line that is followed by invisible text.
     This example is a continuation of the previous one.

          (setq selective-display-ellipses t)
               => t

          ---------- Buffer: foo ----------
          1 on this column
           2on this column ...
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

     You can use a display table to substitute other text for the
     ellipsis (`...').  See Display Tables.

The Overlay Arrow
=================

   The "overlay arrow" is useful for directing the user's attention to
a particular line in a buffer.  For example, in the modes used for
interface to debuggers, the overlay arrow indicates the line of code
about to be executed.

 - Variable: overlay-arrow-string
     This variable holds the string to display to call attention to a
     particular line, or `nil' if the arrow feature is not in use.
     Despite its name, the value of this variable can be either a string
     or a glyph (see Glyphs.).

 - Variable: overlay-arrow-position
     This variable holds a marker that indicates where to display the
     overlay arrow.  It should point at the beginning of a line.  The
     arrow text appears at the beginning of that line, overlaying any
     text that would otherwise appear.  Since the arrow is usually
     short, and the line usually begins with indentation, normally
     nothing significant is overwritten.

     The overlay string is displayed only in the buffer that this marker
     points into.  Thus, only one buffer can have an overlay arrow at
     any given time.

   You can do the same job by creating an extent with a `begin-glyph'
property.  See Extent Properties.

Temporary Displays
==================

   Temporary displays are used by commands to put output into a buffer
and then present it to the user for perusal rather than for editing.
Many of the help commands use this feature.

 - Special Form: with-output-to-temp-buffer BUFFER-NAME FORMS...
     This function executes FORMS while arranging to insert any output
     they print into the buffer named BUFFER-NAME.  The buffer is then
     shown in some window for viewing, displayed but not selected.

     The string BUFFER-NAME specifies the temporary buffer, which need
     not already exist.  The argument must be a string, not a buffer.
     The buffer is erased initially (with no questions asked), and it is
     marked as unmodified after `with-output-to-temp-buffer' exits.

     `with-output-to-temp-buffer' binds `standard-output' to the
     temporary buffer, then it evaluates the forms in FORMS.  Output
     using the Lisp output functions within FORMS goes by default to
     that buffer (but screen display and messages in the echo area,
     although they are "output" in the general sense of the word, are
     not affected).  See Output Functions.

     The value of the last form in FORMS is returned.

          ---------- Buffer: foo ----------
           This is the contents of foo.
          ---------- Buffer: foo ----------

          (with-output-to-temp-buffer "foo"
              (print 20)
              (print standard-output))
          => #<buffer foo>

          ---------- Buffer: foo ----------
          20

          #<buffer foo>

          ---------- Buffer: foo ----------

 - Variable: temp-buffer-show-function
     If this variable is non-`nil', `with-output-to-temp-buffer' calls
     it as a function to do the job of displaying a help buffer.  The
     function gets one argument, which is the buffer it should display.

     In Emacs versions 18 and earlier, this variable was called
     `temp-buffer-show-hook'.

 - Function: momentary-string-display STRING POSITION &optional CHAR
          MESSAGE
     This function momentarily displays STRING in the current buffer at
     POSITION.  It has no effect on the undo list or on the buffer's
     modification status.

     The momentary display remains until the next input event.  If the
     next input event is CHAR, `momentary-string-display' ignores it
     and returns.  Otherwise, that event remains buffered for
     subsequent use as input.  Thus, typing CHAR will simply remove the
     string from the display, while typing (say) `C-f' will remove the
     string from the display and later (presumably) move point forward.
     The argument CHAR is a space by default.

     The return value of `momentary-string-display' is not meaningful.

     You can do the same job in a more general way by creating an extent
     with a begin-glyph property.  See Extent Properties.

     If MESSAGE is non-`nil', it is displayed in the echo area while
     STRING is displayed in the buffer.  If it is `nil', a default
     message says to type CHAR to continue.

     In this example, point is initially located at the beginning of the
     second line:

          ---------- Buffer: foo ----------
          This is the contents of foo.
          -!-Second line.
          ---------- Buffer: foo ----------

          (momentary-string-display
            "**** Important Message! ****"
            (point) ?\r
            "Type RET when done reading")
          => t

          ---------- Buffer: foo ----------
          This is the contents of foo.
          **** Important Message! ****Second line.
          ---------- Buffer: foo ----------

          ---------- Echo Area ----------
          Type RET when done reading
          ---------- Echo Area ----------

     This function works by actually changing the text in the buffer.
     As a result, if you later undo in this buffer, you will see the
     message come and go.

Blinking Parentheses
====================

   This section describes the mechanism by which XEmacs shows a matching
open parenthesis when the user inserts a close parenthesis.

 - Variable: blink-paren-function
     The value of this variable should be a function (of no arguments)
     to be called whenever a character with close parenthesis syntax is
     inserted.  The value of `blink-paren-function' may be `nil', in
     which case nothing is done.

          *Please note:* This variable was named `blink-paren-hook' in
          older Emacs versions, but since it is not called with the
          standard convention for hooks, it was renamed to
          `blink-paren-function' in version 19.

 - Variable: blink-matching-paren
     If this variable is `nil', then `blink-matching-open' does nothing.

 - Variable: blink-matching-paren-distance
     This variable specifies the maximum distance to scan for a matching
     parenthesis before giving up.

 - Variable: blink-matching-paren-delay
     This variable specifies the number of seconds for the cursor to
     remain at the matching parenthesis.  A fraction of a second often
     gives good results, but the default is 1, which works on all
     systems.

 - Function: blink-matching-open
     This function is the default value of `blink-paren-function'.  It
     assumes that point follows a character with close parenthesis
     syntax and moves the cursor momentarily to the matching opening
     character.  If that character is not already on the screen, it
     displays the character's context in the echo area.  To avoid long
     delays, this function does not search farther than
     `blink-matching-paren-distance' characters.

     Here is an example of calling this function explicitly.

          (defun interactive-blink-matching-open ()
            "Indicate momentarily the start of sexp before point."
            (interactive)

          (let ((blink-matching-paren-distance
                   (buffer-size))
                  (blink-matching-paren t))
              (blink-matching-open)))

Usual Display Conventions
=========================

   The usual display conventions define how to display each character
code.  You can override these conventions by setting up a display table
(see Display Tables.).  Here are the usual display conventions:

   * Character codes 32 through 126 map to glyph codes 32 through 126.
     Normally this means they display as themselves.

   * Character code 9 is a horizontal tab.  It displays as whitespace
     up to a position determined by `tab-width'.

   * Character code 10 is a newline.

   * All other codes in the range 0 through 31, and code 127, display
     in one of two ways according to the value of `ctl-arrow'.  If it is
     non-`nil', these codes map to sequences of two glyphs, where the
     first glyph is the ASCII code for `^'.  (A display table can
     specify a glyph to use instead of `^'.)  Otherwise, these codes map
     just like the codes in the range 128 to 255.

   * Character codes 128 through 255 map to sequences of four glyphs,
     where the first glyph is the ASCII code for `\', and the others are
     digit characters representing the code in octal.  (A display table
     can specify a glyph to use instead of `\'.)

   The usual display conventions apply even when there is a display
table, for any character whose entry in the active display table is
`nil'.  Thus, when you set up a display table, you need only specify
the characters for which you want unusual behavior.

   These variables affect the way certain characters are displayed on
the screen.  Since they change the number of columns the characters
occupy, they also affect the indentation functions.

 - User Option: ctl-arrow
     This buffer-local variable controls how control characters are
     displayed.  If it is non-`nil', they are displayed as a caret
     followed by the character: `^A'.  If it is `nil', they are
     displayed as a backslash followed by three octal digits: `\001'.

 - Variable: default-ctl-arrow
     The value of this variable is the default value for `ctl-arrow' in
     buffers that do not override it.  See Default Value.

 - User Option: tab-width
     The value of this variable is the spacing between tab stops used
     for displaying tab characters in Emacs buffers.  The default is 8.
     Note that this feature is completely independent from the
     user-settable tab stops used by the command `tab-to-tab-stop'.
     See Indent Tabs.

Display Tables
==============

   You can use the "display table" feature to control how all 256
possible character codes display on the screen.  This is useful for
displaying European languages that have letters not in the ASCII
character set.

   The display table maps each character code into a sequence of
"runes", each rune being an image that takes up one character position
on the screen.  You can also define how to display each rune on your
terminal, using the "rune table".

Display Table Format
--------------------

   A display table is an array of 256 elements. (In FSF Emacs, a display
table is 262 elements.  The six extra elements specify the truncation
and continuation glyphs, etc.  This method is very kludgey, and in
XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
used.  See Truncation.)

 - Function: make-display-table
     This creates and returns a display table.  The table initially has
     `nil' in all elements.

   The 256 elements correspond to character codes; the Nth element says
how to display the character code N.  The value should be `nil', a
string, a glyph, or a vector of strings and glyphs (see Character Descriptors.).
If an element is `nil', it says to display that
character according to the usual display conventions (see Usual Display.).

   If you use the display table to change the display of newline
characters, the whole buffer will be displayed as one long "line."

   For example, here is how to construct a display table that mimics the
effect of setting `ctl-arrow' to a non-`nil' value:

     (setq disptab (make-display-table))
     (let ((i 0))
       (while (< i 32)
         (or (= i ?\t) (= i ?\n)
             (aset disptab i (concat "^" (char-to-string (+ i 64)))))
         (setq i (1+ i)))
       (aset disptab 127 "^?"))

Active Display Table
--------------------

   The active display table is controlled by the variable
`current-display-table'.  This is a specifier, which means that you can
specify separate values for it in individual buffers, windows, frames,
and devices, as well as a global value.  It also means that you cannot
set this variable using `setq'; use `set-specifier' instead.  See
Specifiers. (FSF Emacs uses `window-display-table',
`buffer-display-table', `standard-display-table', etc. to control the
display table.  However, specifiers are a cleaner and more powerful way
of doing the same thing.  FSF Emacs also uses a different format for
the contents of a display table, using additional indirection to a
"glyph table" and such.  Note that "glyph" has a different meaning in
XEmacs.)

   Individual faces can also specify an overriding display table; this
is set using `set-face-display-table'.  See Faces.

   If no display table can be determined for a particular window, then
XEmacs uses the usual display conventions.  See Usual Display.

Character Descriptors
---------------------

   Each element of the display-table vector describes how to display a
particular character and is called a "character descriptor".  A
character descriptor can be:

a string
     Display this particular string wherever the character is to be
     displayed.

a glyph
     Display this particular glyph wherever the character is to be
     displayed.

a vector
     The vector may contain strings and/or glyphs.  Display the
     elements of the vector one after another wherever the character is
     to be displayed.

`nil'
     Display according to the standard interpretation (see Usual Display.).